Skip to main content

Create your POS instance

In order to create your POS instance on our systems, you’ll need to call us through the following API:

URL:

  • Production environment: POST https://api.thefork.io/pos/v1/create

Headers:

  • X-Api-Key : API key generated in the previous steps
  • Content-Type: application/json

Body:

  • name: Name of the POS Company
  • receiptOpeningUrl: URL of your webhook endpoint to open the order
  • homepageUrl: Website of the POS Company
  • type: Authentication method (currently limited to jwt)
  • oauthClientSecret: the secret you have to generate and provide to us, used in the header for every request made to the POS
  • oauthTokenUrl: Url of the POS API endpoint that we use to link our restaurant instance to the POS one (add the link)

Request example:

API_KEY='Your API Key'

curl --location --request POST 'https://api.thefork.io/pos/v1/create' \
  --header "X-Api-Key: ${API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "name": "Your POS Company name",
      "receiptOpeningUrl": "https://pos.webhook/order",
      "homepageUrl": "https://example.com/something",
      "type": "jwt",
      "oauthClientSecret": "your-secret",
      "oauthTokenUrl": "https://pos.api/link-url"
  }'

Response example (HTTP 200):

{
    "name": "Your POS Company name",
    "type": "jwt",
    "homepageUrl": "https://example.com/something",
    "receiptOpeningUrl": "https://pos.webhook/order",
    "oauthAuthorizeUrl": null,
    "oauthTokenUrl": "https://pos.api/link-url",
    "oauthScope": [],
    "availableOn": [],
    "logoPath": null,
    "uuid": "489cdb94-3c20-4f63-b189-2b095bb879ac",
    "consumerId": "7ee9984a-59d8-4d7c-8d46-dffbfb7e8381"
}

Response error codes:

  • 400 (incorrect payload)
  • 401 (no authorization)
  • 500 (general error, ex. if you try to create a POS with a name that already exists)

The consumerId value uniquely identifies you as a company in our systems, while the uuid value identifies your POS. Ensure to store these values securely for future reference in subsequent calls (like the one to update your logo).

info

After this call the POS instance will be in PENDING state in our production environment and you can start to test your implementation using a test restaurant that we will create (we’ll provide you with the restaurant URL and the TheFork Manager credentials via a secure channel). Once the development phase is complete at your end, we'll run a test session and if all the tests pass, we'll finally activate the POS instance in production.